Appium 3 架构与实战

# Node.js：Appium 3.x 要求 v20.19.0+
node --version
# 输出示例：v22.11.0

# Java：Android Driver 要求 JDK 17+
java --version
# 输出示例：openjdk 21.0.2

# Xcode：iOS Driver 要求 Xcode 16+（2026）
xcodebuild -version
# 输出示例：Xcode 16.4

# 全局安装 Appium 3.x
npm install -g appium

# 验证版本
appium --version
# 输出示例：3.5.0

# 安装 iOS Driver
appium driver install xcuitest

# 安装 Android Driver
appium driver install uiautomator2

# 跨大版本升级（3.x 引入 --unsafe 显式确认）
appium driver update --unsafe

# 查看已安装 Driver
appium driver list --installed
# 输出示例：
# xcuitest      9.1.0   [Installed]
# uiautomator2  4.1.0   [Installed]

# 环境诊断（替代旧的 appium-doctor）
appium doctor

# 列出已连接设备
adb devices

# 启动应用后通过 logcat 抓取入口
adb logcat | grep -i displayed
# 输出示例：com.example.demo/.MainActivity

# 验证入口是否正确
adb shell am start -W -S -n com.example.demo/.MainActivity
# Status: ok 表示入口正确

# Python：通过 UiAutomator2Options 创建 Android Session
from appium import webdriver
from appium.options.android import UiAutomator2Options
from appium.webdriver.appium_service import AppiumService

# 启动 Appium Server（也可独立命令行启动）
service = AppiumService()
service.start(args=["--address", "127.0.0.1", "--port", "4723"])

# 配置 Capabilities（W3C 标准格式，自定义能力加 appium: 前缀）
options = UiAutomator2Options()
options.platform_name = "Android"
options.automation_name = "UiAutomator2"
options.device_name = "Pixel 8 API 34"
options.app_package = "com.example.demo"
options.app_activity = ".MainActivity"
options.set_capability("appium:noReset", True)        # 不重置应用状态
options.set_capability("appium:newCommandTimeout", 120)  # 命令超时 120s

driver = webdriver.Remote("http://127.0.0.1:4723", options)

// Java：使用 AppiumBy 替代旧的 findElementByXxx
import io.appium.java_client.AppiumBy;
import org.openqa.selenium.WebElement;

// 推荐：accessibility id，跨平台一致
WebElement username = driver.findElement(AppiumBy.accessibilityId("username_input"));

// Android 专属：UiSelector 表达式
WebElement loginBtn = driver.findElement(
    AppiumBy.androidUIAutomator("new UiSelector().resourceId(\"com.example.demo:id/btn_login\")")
);

// iOS 专属：predicate string
WebElement title = driver.findElement(
    AppiumBy.iOSNsPredicateString("label == '登录' AND type == 'XCUIElementTypeStaticText'")
);

# Python：常见手势实现
from selenium.webdriver.common.action_chains import ActionChains
from selenium.webdriver.common.actions.action_builder import ActionBuilder
from selenium.webdriver.common.actions.pointer_input import PointerInput
from selenium.webdriver.common.actions import interaction

# 1. tap：单击（坐标）
def tap(driver, x, y):
    actions = ActionChains(driver)
    actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "touch"))
    actions.w3c_actions.pointer_action.move_to_location(x, y).pointer_down().pointer_up()
    actions.perform()

# 2. long_press：长按（按住 2 秒后释放）
def long_press(driver, element):
    ActionChains(driver).click_and_hold(element).pause(2).release().perform()

# 3. swipe：滑动（从 A 点滑到 B 点）
def swipe(driver, x1, y1, x2, y2, duration_ms=800):
    actions = ActionChains(driver)
    actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "touch"))
    actions.w3c_actions.pointer_action.move_to_location(x1, y1).pointer_down()
    actions.w3c_actions.pointer_action.pause(duration_ms / 1000.0)
    actions.w3c_actions.pointer_action.move_to_location(x2, y2).pointer_up()
    actions.perform()

# 4. scroll：滚动到指定元素（Android 专属 mobile: 命令）
driver.execute_script("mobile: scroll", {
    "elementId": element.id,
    "toVisible": True
})

# 5. iOS 专属：mobile: dragFromToForDuration
driver.execute_script("mobile: dragFromToForDuration", {
    "fromX": 100, "fromY": 500,
    "toX": 100, "toY": 200,
    "duration": 0.5
})

# test_android_login.py
import pytest
from appium import webdriver
from appium.options.android import UiAutomator2Options
from appium.webdriver.common.appiumby import AppiumBy

class TestAndroidLogin:
    def setup_method(self):
        # Android Capabilities
        options = UiAutomator2Options()
        options.platform_name = "Android"
        options.automation_name = "UiAutomator2"
        options.device_name = "Pixel 8 API 34"
        options.app_package = "com.example.demo"
        options.app_activity = ".MainActivity"
        options.set_capability("appium:noReset", True)
        options.set_capability("appium:autoGrantPermissions", True)
        options.set_capability("appium:newCommandTimeout", 120)
        self.driver = webdriver.Remote("http://127.0.0.1:4723", options)
        # 隐式等待，移动端建议 ≥ 15 秒
        self.driver.implicitly_wait(15)

    def test_login_success(self):
        # 通过 accessibility id 定位用户名输入框
        username = self.driver.find_element(
            AppiumBy.ACCESSIBILITY_ID, "username_input"
        )
        password = self.driver.find_element(
            AppiumBy.ACCESSIBILITY_ID, "password_input"
        )
        login_btn = self.driver.find_element(
            AppiumBy.ACCESSIBILITY_ID, "login_button"
        )
        # 输入凭据并提交
        username.send_keys("test_user")
        password.send_keys("P@ssw0rd123")
        login_btn.click()
        # 断言登录成功后的欢迎语
        welcome = self.driver.find_element(
            AppiumBy.ACCESSIBILITY_ID, "welcome_label"
        )
        assert welcome.text == "欢迎, test_user"

    def teardown_method(self):
        if self.driver:
            self.driver.quit()

// iOSLoginTest.java
import io.appium.java_client.ios.IOSDriver;
import io.appium.java_client.ios.options.XCUITestOptions;
import io.appium.java_client.AppiumBy;
import org.openqa.selenium.WebElement;
import org.testng.annotations.*;

import java.net.URL;
import java.time.Duration;

public class iOSLoginTest {
    private IOSDriver driver;

    @BeforeTest
    public void setUp() throws Exception {
        // iOS Capabilities：使用 XCUITestOptions 替代 DesiredCapabilities
        XCUITestOptions options = new XCUITestOptions()
            .setPlatformVersion("17.0")
            .setDeviceName("iPhone 15 Pro")
            .setBundleId("com.example.demo")
            .setAutomationName("XCUITest")
            .setNoReset(true)
            .setNewCommandTimeout(Duration.ofSeconds(120))
            // 复用预编译的 WDA，避免每次启动重新编译
            .setUsePrebuiltWDA(true);
        driver = new IOSDriver(new URL("http://127.0.0.1:4723"), options);
        driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(15));
    }

    @Test
    public void testLoginSuccess() {
        // iOS 推荐优先使用 accessibility id，对应 accessibilityIdentifier
        WebElement username = driver.findElement(
            AppiumBy.accessibilityId("username_input")
        );
        WebElement password = driver.findElement(
            AppiumBy.accessibilityId("password_input")
        );
        WebElement loginBtn = driver.findElement(
            AppiumBy.accessibilityId("login_button")
        );
        username.sendKeys("test_user");
        password.sendKeys("P@ssw0rd123");
        loginBtn.click();

        // 等待欢迎语出现并断言
        WebElement welcome = driver.findElement(
            AppiumBy.accessibilityId("welcome_label")
        );
        assert welcome.getText().equals("欢迎, test_user") :
            "登录失败，实际文案: " + welcome.getText();
    }

    @AfterTest
    public void tearDown() {
        if (driver != null) {
            driver.quit();
        }
    }
}